home *** CD-ROM | disk | FTP | other *** search
/ Aminet 48 / Aminet 48 (2002)(GTI - Schatztruhe)[!][Apr 2002].iso / Aminet / text / edit / vim60rt.lha / Vim / vim60 / doc / change.txt < prev    next >
Encoding:
Text File  |  2001-09-26  |  51.7 KB  |  1,306 lines
  1. *change.txt*    For Vim version 6.0.  Last change: 2001 Sep 11
  2.  
  3.  
  4.           VIM REFERENCE MANUAL    by Bram Moolenaar
  5.  
  6.  
  7. This file describes commands that delete or change text.  In this context,
  8. changing text means deleting the text and replacing it with other text using
  9. one command.  You can undo all of these commands.  You can repeat the non-Ex
  10. commands with the "." command.
  11.  
  12. 1. Deleting text        |deleting|
  13. 2. Delete and insert        |delete-insert|
  14. 3. Simple changes        |simple-change|        *changing*
  15. 4. Complex changes        |complex-change|
  16. 5. Copying and moving text    |copy-move|
  17. 6. Formatting text        |formatting|
  18.  
  19. For inserting text see |insert.txt|.
  20.  
  21. ==============================================================================
  22. 1. Deleting text                    *deleting*
  23.  
  24. ["x]<Del>    or                    *<Del>* *x* *dl*
  25. ["x]x            Delete [count] characters under and after the cursor
  26.             [into register x] (not linewise).  Does the same as
  27.             "dl".
  28.             The <Del> key does not take a [count].  Instead, it
  29.             deletes the last character of the count.
  30.             See |:fixdel| if the <Del> key does not do what you
  31.             want.  See |'whichwrap'| for deleting a line break
  32.             (join lines).  {Vi does not support <Del>}
  33.  
  34.                             *X* *dh*
  35. ["x]X            Delete [count] characters before the cursor [into
  36.             register x] (not linewise).  Does the same as "dh".
  37.             Also see |'whichwrap'|.
  38.  
  39.                             *d*
  40. ["x]d{motion}        Delete text that {motion} moves over [into register
  41.             x].  See below for exceptions.
  42.  
  43.                             *dd*
  44. ["x]dd            Delete [count] lines [into register x] (linewise).
  45.  
  46.                             *D*
  47. ["x]D            Delete the characters under the cursor until the end
  48.             of the line and [count]-1 more lines [into register
  49.             x]; synonym for d$ (not linewise).
  50.  
  51. {Visual}["x]x    or                    *v_x* *v_d* *v_<Del>*
  52. {Visual}["x]d   or
  53. {Visual}["x]<Del>    Delete the highlighted text [into register x] (for
  54.             {Visual} see |Visual-mode|).  {not in Vi}
  55.  
  56. {Visual}["x]CTRL-H   or                    *v_CTRL-H* *v_<BS>*
  57. {Visual}["x]<BS>    When in Select mode: Delete the highlighted text [into
  58.             register x].
  59.  
  60. {Visual}["x]X    or                    *v_X* *v_D* *v_b_D*
  61. {Visual}["x]D        Delete the highlighted lines [into register x] (for
  62.             {Visual} see |Visual-mode|).  In Visual block mode,
  63.             "D" deletes the highlighted text plus all text until
  64.             the end of the line.  {not in Vi}
  65.  
  66.                         *:d* *:de* *:del* *:delete*
  67. :[range]d[elete] [x]    Delete [range] lines (default: current line) [into
  68.             register x].
  69.  
  70. :[range]d[elete] [x] {count}
  71.             Delete {count} lines, starting with [range]
  72.             (default: current line |cmdline-ranges|) [into
  73.             register x].
  74.  
  75. These commands delete text.  You can repeat them with the "." command
  76. (except ":d") and undo them.  Use Visual mode to delete blocks of text.  See
  77. |registers| for an explanation of registers.
  78.  
  79. An exception for the d{motion} command: If the motion is not linewise, the
  80. start and end of the motion are not in the same line, and there are only
  81. blanks before the start and after the end of the motion, the delete becomes
  82. linewise.  This means that the delete also removes the line of blanks that you
  83. might expect to remain.
  84.  
  85. Trying to delete an empty region of text (e.g., "d0" in the first column)
  86. is an error when 'cpoptions' includes the 'E' flag.
  87.  
  88.                             *J*
  89. J            Join [count] lines, with a minimum of two lines.
  90.             Remove the indent and insert up to two spaces (see
  91.             below).
  92.  
  93.                             *v_J*
  94. {Visual}J        Join the highlighted lines, with a minimum of two
  95.             lines.  Remove the indent and insert up to two spaces
  96.             (see below).  {not in Vi}
  97.  
  98.                             *gJ*
  99. gJ            Join [count] lines, with a minimum of two lines.
  100.             Don't insert or remove any spaces.  {not in Vi}
  101.  
  102.                             *v_gJ*
  103. {Visual}gJ        Join the highlighted lines, with a minimum of two
  104.             lines.  Don't insert or remove any spaces.  {not in
  105.             Vi}
  106.  
  107.                             *:j* *:join*
  108. :[range]j[oin][!]    Join [range] lines.  Same as "J", except with [!]
  109.             the join does not insert or delete any spaces.
  110.             If a [range] has equal start and end values, this
  111.             command does nothing.  The default behavior is to
  112.             join the current line with the line below it.
  113.             {not in Vi: !}
  114.  
  115. :[range]j[oin][!] {count}
  116.             Join {count} lines, starting with [range] (default:
  117.             current line |cmdline-ranges|).  Same as "J", except
  118.             with [!] the join does not insert or delete any
  119.             spaces.
  120.             {not in Vi: !}
  121.  
  122. These commands delete the <EOL> between lines.  This has the effect of joining
  123. multiple lines into one line.  You can repeat these commands (except ":j") and
  124. undo them.
  125.  
  126. These commands, except "gJ", insert one space in place of the <EOL> unless
  127. there is trailing white space or the next line starts with a ')'.  These
  128. commands, except "gJ", delete any leading white space on the next line.  If
  129. the 'joinspaces' option is on, these commands insert two spaces after a '.',
  130. '!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces
  131. only after a '.').
  132.  
  133.  
  134. ==============================================================================
  135. 2. Delete and insert                *delete-insert* *replacing*
  136.  
  137.                             *R*
  138. R            Enter Replace mode: Each character you type replaces
  139.             an existing character, starting with the character
  140.             under the cursor.  Repeat the entered text [count]-1
  141.             times.  See |Replace-mode| for more details.
  142.  
  143.                             *gR*
  144. gR            Enter Virtual replace mode: Each character you type
  145.             replaces existing characters in screen space.  So a
  146.             <Tab> may replace several characters at once.
  147.             Repeat the entered text [count]-1 times.  See
  148.             |Virtual-replace-mode| for more details.
  149.             {not available when compiled without the +vreplace
  150.             feature}
  151.  
  152.                             *c*
  153. ["x]c{motion}        Delete {motion} text [into register x] and start
  154.             insert.  When  'cpoptions' includes the 'E' flag and
  155.             there is no text to delete (e.g., with "cTx" when the
  156.             cursor is just after an 'x'), an error occurs and
  157.             insert mode does not start (this is Vi compatible).
  158.             When  'cpoptions' does not include the 'E' flag, the
  159.             "c" command always starts insert mode, even if there
  160.             is no text to delete.
  161.  
  162.                             *cc*
  163. ["x]cc            Delete [count] lines [into register x] and start
  164.             insert (linewise).  If 'autoindent' is on, preserve
  165.             the indent of the first line.
  166.  
  167.                             *C*
  168. ["x]C            Delete from the cursor position to the end of the
  169.             line and [count]-1 more lines [into register x], and
  170.             start insert.  Synonym for c$ (not linewise).
  171.  
  172.                             *s*
  173. ["x]s            Delete [count] characters [into register x] and start
  174.             insert (s stands for Substitute).  Synonym for "cl"
  175.             (not linewise).
  176.  
  177.                             *S*
  178. ["x]S            Delete [count] lines [into register x] and start
  179.             insert.  Synonym for "cc" (linewise).
  180.  
  181. {Visual}["x]c    or                    *v_c* *v_s*
  182. {Visual}["x]s        Delete the highlighted text [into register x] and
  183.             start insert (for {Visual} see |Visual-mode|).  {not
  184.             in Vi}
  185.  
  186.                             *v_r*
  187. {Visual}["x]r{char}    Replace all selected characters by {char}.
  188.  
  189.                             *v_C*
  190. {Visual}["x]C        Delete the highlighted lines [into register x] and
  191.             start insert.  In Visual block mode it works
  192.             differently |v_b_C|.  {not in Vi}
  193.                             *v_S*
  194. {Visual}["x]S        Delete the highlighted lines [into register x] and
  195.             start insert (for {Visual} see |Visual-mode|).  {not
  196.             in Vi}
  197.                             *v_R*
  198. {Visual}["x]R        Currently just like {Visual}["x]S.  In a next version
  199.             it might work differently. {not in Vi}
  200.  
  201. Notes:
  202. - You can end Insert and Replace mode with <Esc>.
  203. - See the section "Insert and Replace mode" |mode-ins-repl| for the other
  204.   special characters in these modes.
  205. - The effect of [count] takes place after Vim exits Insert or Replace mode.
  206. - When the 'cpoptions' option contains '$' and the change is within one line,
  207.   Vim continues to show the text to be deleted and puts a '$' at the last
  208.   deleted character.
  209.  
  210. See |registers| for an explanation of registers.
  211.  
  212. Replace mode is just like Insert mode, except that every character you enter
  213. deletes one character.  If you reach the end of a line, Vim appends any
  214. further characters (just like Insert mode).  In Replace mode, the backspace
  215. key restores the original text (if there was any).  (See section "Insert and
  216. Replace mode" |mode-ins-repl|).
  217.  
  218.                         *cw* *cW*
  219. Special case: "cw" and "cW" work the same as "ce" and "cE" if the cursor is
  220. on a non-blank.  This is because Vim interprets "cw" as change-word, and a
  221. word does not include the following white space.  {Vi: "cw" when on a blank
  222. followed by other blanks changes only the first blank; this is probably a
  223. bug, because "dw" deletes all the blanks; use the 'w' flag in 'cpoptions' to
  224. make it work like Vi anyway}
  225.  
  226. If you prefer "cw" to include the space after a word, use this mapping: >
  227.     :map cw dwi
  228. <
  229.                             *:c* *:ch* *:change*
  230. :{range}c[hange]    Replace lines of text with some different text.
  231.             Type a line containing only "." to stop replacing.
  232.             Without {range}, this command changes only the current
  233.             line.
  234.  
  235. ==============================================================================
  236. 3. Simple changes                    *simple-change*
  237.  
  238.                             *r*
  239. r{char}            Replace the character under the cursor with {char}.
  240.             If {char} is a <CR> or <NL>, a line break replaces the
  241.             character.  To replace with a real <CR>, use CTRL-V
  242.             <CR>.  CTRL-V <NL> replaces with a <Nul>.
  243.             {Vi: CTRL-V <CR> still replaces with a line break,
  244.             cannot replace something with a <CR>}
  245.             If you give a [count], Vim replaces [count] characters
  246.             with [count] {char}s.  When {char} is a <CR> or <NL>,
  247.             however, Vim inserts only one <CR>: "5r<CR>" replaces
  248.             five characters with a single line break.
  249.             When {char} is a <CR> or <NL>, Vim performs
  250.             autoindenting.  This works just like deleting the
  251.             characters that are replaced and then doing
  252.             "i<CR><Esc>".
  253.             {char} can be entered as a digraph |digraph-arg|.
  254.             |:lmap| mappings apply to {char}.  The CTRL-^ command
  255.             in Insert mode can be used to switch this on/off
  256.             |i_CTRL-^|.  See |utf-8-char-arg| about using
  257.             composing characters when 'encoding' is Unicode.
  258.  
  259.                             *gr*
  260. gr{char}        Replace the virtual characters under the cursor with
  261.             {char}.  This replaces in screen space, not file
  262.             space.  See |gR| and |Virtual-replace-mode| for more
  263.             details.  As with |r| a count may be given.
  264.             {char} can be entered like with |r|.
  265.             {not available when compiled without the +vreplace
  266.             feature}
  267.  
  268.                         *digraph-arg*
  269. The argument for Normal mode commands like |r| and |t| is a single character.
  270. When 'cpo' doesn't contain the 'D' flag, this character can also be entered
  271. like |digraphs|.  First type CTRL-K and then the two digraph characters.
  272. {not available when compiled without the |+digraphs| feature}
  273.  
  274.                         *case*
  275. The following commands change the case of letters.  The currently active
  276. |locale| is used.  See |:language|.  The LC_CTYPE value matters here.
  277.  
  278.                             *~*
  279. ~            'notildeop' option: Switch case of the character
  280.             under the cursor and move the cursor to the right.
  281.             If a [count] is given, do that many characters. {Vi:
  282.             no count}
  283.  
  284. ~{motion}        'tildeop' option: switch case of {motion} text. {Vi:
  285.             tilde cannot be used as an operator}
  286.  
  287.                             *g~*
  288. g~{motion}        Switch case of {motion} text. {not in Vi}
  289.  
  290. g~g~                            *g~g~* *g~~*
  291. g~~            Switch case of current line. {not in Vi}.
  292.  
  293.                             *v_~*
  294. {Visual}~        Switch case of highlighted text (for {Visual} see
  295.             |Visual-mode|). {not in Vi}
  296.  
  297.                             *v_U*
  298. {Visual}U        Make highlighted text uppercase (for {Visual} see
  299.             |Visual-mode|). {not in Vi}
  300.  
  301.                             *gU* *uppercase*
  302. gU{motion}        Make {motion} text uppercase. {not in Vi}
  303.             Example: >
  304.                 :map! <C-F> <Esc>gUiw`]a
  305. <            This works in Insert mode: press CTRL-F to make the
  306.             word before the cursor uppercase.  Handy to type
  307.             words in lowercase and then make them uppercase.
  308.  
  309.  
  310. gUgU                            *gUgU* *gUU*
  311. gUU            Make current line uppercase. {not in Vi}.
  312.  
  313.                             *v_u*
  314. {Visual}u        Make highlighted text lowercase (for {Visual} see
  315.             |Visual-mode|).  {not in Vi}
  316.  
  317.                             *gu* *lowercase*
  318. gu{motion}        Make {motion} text lowercase. {not in Vi}
  319.  
  320. gugu                            *gugu* *guu*
  321. guu            Make current line lowercase. {not in Vi}.
  322.  
  323.                             *g?* *rot13*
  324. g?{motion}        Rot13 encode {motion} text. {not in Vi}
  325.  
  326.                             *v_g?*
  327. {Visual}g?        Rot13 encode the highlighted text (for {Visual} see
  328.             |Visual-mode|).  {not in Vi}
  329.  
  330. g?g?                            *g?g?* *g??*
  331. g??            Rot13 encode current line. {not in Vi}.
  332.  
  333.  
  334. Adding and subtracting ~
  335.                             *CTRL-A*
  336. CTRL-A            Add [count] to the number or alphabetic character at
  337.             or after the cursor.  {not in Vi}
  338.  
  339.                             *CTRL-X*
  340. CTRL-X            Subtract [count] from the number or alphabetic
  341.             character at or after the cursor.  {not in Vi}
  342.  
  343. The CTRL-A and CTRL-X commands work for (signed) decimal numbers, unsigned
  344. octal and hexadecimal numbers and alphabetic characters.  This depends on the
  345. 'nrformats' option.
  346. - When 'nrformats' includes "alpha", Vim will change the alphabetic character
  347.   under or after the cursor.  This is useful to make lists with an alphabetic
  348.   index.
  349. - When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or
  350.   '0X' are hexadecimal.  The case of the rightmost letter in the number
  351.   determines the case of the resulting hexadecimal number.  If there is no
  352.   letter in the current number, Vim uses the previously detected case.
  353. - When 'nrformats' includes "octal", Vim considers numbers starting with a '0'
  354.   to be octal.  Other numbers are decimal and may have a preceding minus sign.
  355.   If the cursor is on a number, the commands apply to that number; otherwise
  356.   Vim uses the number to the right of the cursor.
  357.  
  358. For numbers with leading zeros (including all octal and hexadecimal numbers),
  359. Vim preserves the number of characters in the number when possible.  CTRL-A on
  360. "0077" results in "0100", CTRL-X on "0x100" results in "0x0ff".  Note that
  361. when 'nrformats' includes "octal", decimal numbers with leading zeros are
  362. impossible because they are indistinguishable from octal numbers.
  363.  
  364. The CTRL-A command is very useful in a macro.  Example: Use the following
  365. steps to make a numbered list.
  366.  
  367. 1. Create the first list entry, make sure it starts with a number.
  368. 2. qa         - start recording into buffer 'a'
  369. 3. Y         - yank the entry
  370. 4. p         - put a copy of the entry below the first one
  371. 5. CTRL-A    - increment the number
  372. 6. q         - stop recording
  373. 7. <count>@a - repeat the yank, put and increment <count> times
  374.  
  375.  
  376. SHIFTING LINES LEFT OR RIGHT                *shift-left-right*
  377.  
  378.                             *<*
  379. <{motion}        Shift {motion} lines one 'shiftwidth' leftwards.
  380.  
  381.                             *<<*
  382. <<            Shift [count] lines one 'shiftwidth' leftwards.
  383.  
  384.                             *v_<*
  385. {Visual}[count]<    Shift the highlighted lines [count] 'shiftwidth'
  386.             leftwards (for {Visual} see |Visual-mode|).  {not in
  387.             Vi}
  388.  
  389.                             *>*
  390.  >{motion}        Shift {motion} lines one 'shiftwidth' rightwards.
  391.  
  392.                             *>>*
  393.  >>            Shift [count] lines one 'shiftwidth' rightwards.
  394.  
  395.                             *v_>*
  396. {Visual}[count]>    Shift the highlighted lines [count] 'shiftwidth'
  397.             rightwards (for {Visual} see |Visual-mode|).  {not in
  398.             Vi}
  399.  
  400.                             *:<*
  401. :[range]<        Shift [range] lines one 'shiftwidth' left.  Repeat '<'
  402.             for shifting multiple 'shiftwidth's.
  403.  
  404. :[range]< {count}    Shift {count} lines one 'shiftwidth' left, starting
  405.             with [range] (default current line |cmdline-ranges|).
  406.             Repeat '<' for shifting multiple 'shiftwidth's.
  407.  
  408. :[range]le[ft] [indent]    left align lines in [range].  Sets the indent in the
  409.             lines to [indent] (default 0).  {not in Vi}
  410.  
  411.                             *:>*
  412. :[range]>        Shift {count} [range] lines one 'shiftwidth' right.
  413.             Repeat '>' for shifting multiple 'shiftwidth's.
  414.  
  415. :[range]> {count}    Shift {count} lines one 'shiftwidth' right, starting
  416.             with [range] (default current line |cmdline-ranges|).
  417.             Repeat '>' for shifting multiple 'shiftwidth's.
  418.  
  419. The ">" and "<" commands are handy for changing the indentation within
  420. programs.  Use the 'shiftwidth' option to set the size of the white space
  421. which these commands insert or delete.  Normally the 'shiftwidth' option is 8,
  422. but you can set it to, say, 3 to make smaller indents.  The shift leftwards
  423. stops when there is no indent.  The shift right does not affect empty lines.
  424.  
  425. If the 'shiftround' option is on, the indent is rounded to a multiple of
  426. 'shiftwidth'.
  427.  
  428. If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains
  429. '#', shift right does not affect lines starting with '#' (these are supposed
  430. to be C preprocessor lines that must stay in column 1).
  431.  
  432. When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as
  433. much as possible to make the indent.  You can use ">><<" to replace an indent
  434. made out of spaces with the same indent made out of <Tab>s (and a few spaces
  435. if necessary).  If the 'expandtab' option is on, Vim uses only spaces.  Then
  436. you can use ">><<" to replace <Tab>s in the indent by spaces (or use
  437. ":retab!").
  438.  
  439. To move a line several 'shiftwidth's, use Visual mode or the ":" commands.
  440. For example: >
  441.     Vjj4>        move three lines 4 indents to the right
  442.     :<<<        move current line 3 indents to the left
  443.     :>> 5        move 5 lines 2 indents to the right
  444.     :5>>        move line 5 2 indents to the right
  445.  
  446. ==============================================================================
  447. 4. Complex changes                    *complex-change*
  448.  
  449.                             *!* *filter*
  450. !{motion}{filter}    Filter {motion} text through the external program
  451.             {filter}.
  452.  
  453.                             *!!*
  454. !!{filter}        Filter [count] lines through the external program
  455.             {filter}.
  456.  
  457.                             *v_!*
  458. {Visual}!{filter}    Filter the highlighted lines through the external
  459.             program {filter} (for {Visual} see |Visual-mode|).
  460.             {not in Vi}
  461.  
  462. :{range}![!]{filter} [!][arg]                *:range!*
  463.             Filter {range} lines through the external program
  464.             {filter}.  Vim replaces the optional bangs with the
  465.             latest given command and appends the optional [arg].
  466.             Vim saves the output of the filter command in a
  467.             temporary file and then reads the file into the
  468.             buffer.  Vim uses the 'shellredir' option to redirect
  469.             the filter output to the temporary file.
  470.  
  471.                             *=*
  472. ={motion}        Filter {motion} lines through the external program
  473.             given with the 'equalprg' option.  When the 'equalprg'
  474.             option is empty (this is the default), use the
  475.             internal formatting function |C-indenting|.  But when
  476.             'indentexpr' is not empty, it will be used instead
  477.             |indent-expression|.
  478.  
  479.                             *==*
  480. ==            Filter [count] lines like with ={motion}.
  481.  
  482.                             *v_=*
  483. {Visual}=        Filter the highlighted lines like with ={motion}.
  484.             {not in Vi}
  485.  
  486. A filter is a program that accepts text at standard input, changes it in some
  487. way, and sends it to standard output.  You can use the commands above to send
  488. some text through a filter.  Examples of filters are "sort", which sorts lines
  489. alphabetically, and "indent", which formats C program files (you need a
  490. version of indent that works like a filter; not all versions do).  The 'shell'
  491. option specifies the shell Vim uses to execute the filter command (See also
  492. the 'shelltype' option).  You can repeat filter commands with ".".  Vim does
  493. not recognize a comment (starting with '"') after the ":!" command.
  494.  
  495.  
  496.                         *:s* *:su* *:substitute*
  497. :[range]s[ubstitute]/{pattern}/{string}/[&][c][e][g][p][r][i][I] [count]
  498.             For each line in [range] replace a match of {pattern}
  499.             with {string}.
  500.             {string} can be a literal string, or something
  501.             special; see |sub-replace-special|.
  502.             When [range] and [count] are omitted, replace in the
  503.             current line only.
  504.             When [count] is given, replace in [count] lines,
  505.             starting with the last line in [range].  When [range]
  506.             is omitted start in the current line.
  507.             Also see |cmdline-ranges|.
  508.             See |:s_flags| for the flags.
  509.  
  510. :[range]s[ubstitute] [c][e][g][p][r][i][I] [count]
  511. :[range]&[&][c][e][g][p][r][i][I] [count]            *:&*
  512.             Repeat last :substitute with same search pattern and
  513.             substitute string, but without the same flags.  You
  514.             may add extra flags (see |:s_flags|).
  515.             Note that after ":substitute" the '&' flag can't be
  516.             used, it's recognized as a pattern separator.
  517.             The space between ":substitute" and the 'c', 'g' and
  518.             'r' flags isn't required, but in scripts it's a good
  519.             idea to keep it to avoid confusion.
  520.  
  521. :[range]~[&][c][e][g][p][r][i][I] [count]            *:~*
  522.             Repeat last substitute with same substitute string
  523.             but with last used search pattern.  This is like
  524.             ":&r".  See |:s_flags| for the flags.
  525.  
  526.                         *&*
  527. &            Synonym for ":s//~/" (repeat last substitute).  Note
  528.             that the flags are not remembered, thus it might
  529.             actually work differently.  You can use ":&&" to keep
  530.             the flags.
  531.  
  532.                         *g&*
  533. g&            Synonym for ":%s//~/&" (repeat last substitute on all
  534.             lines with the same flags).
  535.             Mnemonic: global substitute. {not in Vi}
  536.  
  537.                         *:snomagic*
  538. :[range]sno[magic] ...    Same as ":substitute", but always use 'nomagic'.
  539.             {not in Vi}
  540.  
  541.                         *:smagic*
  542. :[range]sm[agic] ...    Same as ":substitute", but always use 'magic'.
  543.             {not in Vi}
  544.  
  545.                             *:s_flags*
  546. The flags that you can use for the substitute commands:
  547.  
  548. [&]    Must be the first one: Keep the flags from the previous substitute
  549.     command.  Examples: >
  550.         :&&
  551.         :s/this/that/&
  552. <    Note that ":s" and ":&" don't keep the flags.
  553.     {not in Vi}
  554.  
  555. [c]    Confirm each substitution.  Vim highlights the matching string (with
  556.     |hl-IncSearch|).  You can type:                *:s_c*
  557.         'y'        to substitute this match
  558.         'l'        to substitute this match and then quit ("last")
  559.         'n'        to skip this match
  560.         <Esc>   to quit substituting
  561.         'a'        to substitute this and all remaining matches {not in Vi}
  562.         'q'        to quit substituting {not in Vi}
  563.         CTRL-E  to scroll the screen up {not in Vi, not available when
  564.             compiled without the +insert_expand feature}
  565.         CTRL-Y  to scroll the screen down {not in Vi, not available when
  566.             compiled without the +insert_expand feature}
  567.     If the 'edcompatible' option is on, Vim remembers the [c] flag and
  568.     toggles it each time you use it, but resets it when you give a new
  569.     search pattern.
  570.     {not in Vi: highlighting of the match, other responses than 'y' or 'n'}
  571.  
  572. [e]     When the search pattern fails, do not issue an error message and, in
  573.     particular, continue in maps as if no error occurred.  This is most
  574.     useful to prevent the "No match" error from breaking a mapping.  Vim
  575.     does not suppress the following error messages, however:
  576.         Regular expressions can't be delimited by letters
  577.         \ should be followed by /, ? or &
  578.         No previous substitute regular expression
  579.         Trailing characters
  580.         Interrupted
  581.     {not in Vi}
  582.  
  583. [g]    Replace all occurrences in the line.  Without this argument,
  584.     replacement occurs only for the first occurrence in each line.  If
  585.     the 'edcompatible' option is on, Vim remembers this flag and toggles
  586.     it each time you use it, but resets it when you give a new search
  587.     pattern.  If the 'gdefault' option is on, this flag is on by default
  588.     and the [g] argument switches it off.
  589.  
  590. [i]    Ignore case for the pattern.  The 'ignorecase' and 'smartcase' options
  591.     are not used.
  592.     {not in Vi}
  593.  
  594. [I]    Don't ignore case for the pattern.  The 'ignorecase' and 'smartcase'
  595.     options are not used.
  596.     {not in Vi}
  597.  
  598. [p]    Print the line containing the last substitute.
  599.     {not in Vi}
  600.  
  601. [r]    Only useful in combination with ":&" or ":s" without arguments.  ":&r"
  602.     works the same way as ":~":  When the search pattern is empty, use the
  603.     previously used search pattern instead of the search pattern from the
  604.     last substitute or ":global".  If the last command that did a search
  605.     was a substitute or ":global", there is no effect.  If the last
  606.     command was a search command such as "/", use the pattern from that
  607.     command.
  608.     For ":s" with an argument this already happens: >
  609.         :s/blue/red/
  610.         /green
  611.         :s//red/   or  :~   or  :&r
  612. <    The last commands will replace "green" with "red". >
  613.         :s/blue/red/
  614.         /green
  615.         :&
  616. <    The last command will replace "blue" with "red".
  617.     {not in Vi}
  618.  
  619. Note that there is no flag to change the "magicness" of the pattern.  A
  620. different command is used instead.  The reason is that the flags can only be
  621. found by skipping the pattern, and in order to skip the pattern the
  622. "magicness" must be known.  Catch 22!
  623.  
  624. If the {pattern} for the substitute command is empty, the command uses the
  625. pattern from the last substitute or ":global" command.  With the [r] flag, the
  626. command uses the pattern from the last substitute, ":global", or search
  627. command.
  628.  
  629. For compatibility with Vi these two exceptions are allowed:
  630. "\/{string}/" and "\?{string}?" do the same as "//{string}/r".
  631. "\&{string}&" does the same as "//{string}/".
  632.                             *E146*
  633. Instead of the '/' which surrounds the pattern and replacement string, you
  634. can use any other character, but not an alphanumeric character, '\', '"' or
  635. '|'.  This is useful if you want to include a '/' in the search pattern or
  636. replacement string.  Example: >
  637.     :s+/+//+
  638.  
  639. For the definition of a pattern, see |pattern|.
  640.  
  641.                         *sub-replace-special*
  642. When the {string} starts with "\=" it is evaluated as an expression.  The
  643. special meaning for characters as mentioned below does not apply then.
  644. The whole matched text can be accessed with "submatch(0)".  The text matched
  645. with the first pair of () with "submatch(1)".  Likewise for further
  646. sub-matches in ().
  647. Be careful: The separation character must not appear in the expression!
  648. Consider using a character like "@" or "|".
  649. Example: >
  650.     :s@\n@\="\r" . expand("$HOME") . "\r"@
  651. This replaces an end-of-line with a new line containing the value of $HOME.
  652.  
  653. Some characters in {string} have a special meaning:
  654.  
  655. magic    nomagic      action    ~
  656.   &      \&      replaced with the whole matched pattern
  657.  \&       &      replaced with &
  658.       \0      replaced with the whole matched pattern  *\0*
  659.       \1      replaced with the matched pattern in the first pair of ()
  660.       \2      replaced with the matched pattern in the second pair of ()
  661.       ..      ..
  662.       \9      replaced with the matched pattern in the ninth pair of ()
  663.   ~      \~      replaced with the {string} of the previous substitute
  664.  \~       ~      replaced with ~ 
  665.       \u      next character made uppercase
  666.       \U      following characters made uppercase
  667.       \l      next character made lowercase
  668.       \L      following characters made lowercase
  669.       \e      end of \u, \U, \l and \L (NOTE: not <Esc>!)
  670.       \E      end of \u, \U, \l and \L
  671.       <CR>      split line in two at this point (Type the <CR> as CTRL-V
  672.           <Enter>)
  673.       \r      idem
  674.       \<CR>      insert a carriage-return (CTRL-M) (Type the <CR> as CTRL-V
  675.           <Enter>)
  676.       \n      insert a <NL> (<NUL> in the file) (does NOT break the line)
  677.       \b      insert a <BS>
  678.       \t      insert a <Tab>
  679.       \\      insert a single backslash
  680.       \x      where x is any character not mentioned above: Reserved for
  681.           future expansion
  682.  
  683. Examples: >
  684.   :s/a\|b/xxx\0xxx/g         modifies "a b"         to "xxxaxxx xxxbxxx"
  685.   :s/\([abc]\)\([efg]\)/\2\1/g     modifies "af fa bg" to "fa fa gb"
  686.   :s/abcde/abc^Mde/         modifies "abcde"    to "abc", "de" (two lines)
  687.   :s/$/\^M/             modifies "abcde"    to "abcde^M"
  688.  
  689. Note: In previous versions CTRL-V was handled in a special way.  Since this is
  690. not Vi compatible, this was removed.  Use a backslash instead.
  691.  
  692. command        text    result ~
  693. :s/aa/a^Ma/    aa    a<line-break>a
  694. :s/aa/a\^Ma/    aa    a^Ma
  695. :s/aa/a\\^Ma/    aa    a\<line-break>a
  696.  
  697. (you need to type CTRL-V <CR> to get a ^M here)
  698.  
  699. The numbering of "\1", "\2" etc. is done based on which "\(" comes first in
  700. the pattern (going left to right).  When a parentheses group matches several
  701. times, the last one will be used for "\1", "\2", etc.  Example: >
  702.   :s/\(\(a[a-d] \)*\)/\2/      modifies "aa ab x" to "ab x"
  703.  
  704. When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\),
  705. either the first or second pattern in parentheses did not match, so either
  706. \1 or \2 is empty.  Example: >
  707.   :s/\([ab]\)\|\([cd]\)/\1x/g   modifies "a b c d"  to "ax bx x x"
  708. <
  709.                         *:pro* *:promptfind*
  710. :promptf[ind] [string]
  711.             Put up a Search dialog.  When [string] is given, it is
  712.             used as the initial search string.
  713.             {only for Win32, Motif and GTK GUI}
  714.  
  715.                         *:promptr* *:promptrepl*
  716. :promptr[epl] [string]
  717.             Put up a Search/Replace dialog.  When [string] is
  718.             given, it is used as the initial search string.
  719.             {only for Win32, Motif and GTK GUI}
  720.  
  721.                             *:ret* *:retab*
  722. :[range]ret[ab][!] [new_tabstop]
  723.             Replace all sequences of white-space containing a
  724.             <Tab> with new strings of white-space using the new
  725.             tabstop value given.  If you do not specify a new
  726.             tabstop size, Vim uses the current value of 'tabstop'.
  727.             The current value of 'tabstop' is always used to
  728.             compute the width of existing tabs.
  729.             With !, Vim also replaces strings of only normal
  730.             spaces with tabs where appropriate.
  731.             With 'expandtab' on, Vim replaces all tabs with the
  732.             appropriate number of spaces.
  733.             This command sets 'tabstop' to the new value given,
  734.             and if performed on the whole file, which is default,
  735.             should not make any visible change.
  736.             Careful: This command modifies any <Tab> characters
  737.             inside of strings in a C program.  Use "\t" to avoid
  738.             this (that's a good habit anyway).
  739.             ":retab!" may also change a sequence of spaces by
  740.             <Tab> characters, which can mess up a printf().
  741.             {not in Vi}
  742.             Not available when |+ex_extra| feature was disabled at
  743.             compile time.
  744.  
  745.                             *retab-example*
  746. Example for using autocommands and ":retab" to edit a file which is stored
  747. with tabstops at 8 but edited with tabstops set at 4.  Warning: white space
  748. inside of strings can change!  Also see 'softtabstop' option. >
  749.  
  750.   :auto BufReadPost    *.xx    retab! 4
  751.   :auto BufWritePre    *.xx    retab! 8
  752.   :auto BufWritePost    *.xx    retab! 4
  753.   :auto BufNewFile    *.xx    set ts=4
  754.  
  755. ==============================================================================
  756. 5. Copying and moving text                *copy-move*
  757.  
  758.                             *quote*
  759. "{a-zA-Z0-9.%#:-"}    Use register {a-zA-Z0-9.%#:-"} for next delete, yank
  760.             or put (use uppercase character to append with
  761.             delete and yank) ({.%#:} only work with put).
  762.  
  763.                             *:reg* *:registers*
  764. :reg[isters]        Display the contents of all numbered and named
  765.             registers.  {not in Vi}
  766.  
  767. :reg[isters] {arg}    Display the contents of the numbered and named
  768.             registers that are mentioned in {arg}.  For example: >
  769.                 :dis 1a
  770. <            to display registers '1' and 'a'.  Spaces are allowed
  771.             in {arg}.  {not in Vi}
  772.  
  773.                             *:di* *:display*
  774. :di[splay] [arg]    Same as :registers.  {not in Vi}
  775.  
  776.                             *y* *yank*
  777. ["x]y{motion}        Yank {motion} text [into register x].  When no
  778.             characters are to be yanked (e.g., "y0" in column 1),
  779.             this is an error when 'cpoptions' includes the 'E'
  780.             flag.
  781.  
  782.                             *yy*
  783. ["x]yy            Yank [count] lines [into register x] (linewise).
  784.  
  785.                             *Y*
  786. ["x]Y            yank [count] lines [into register x] (synonym for
  787.             yy, linewise).  If you like "Y" to work from the
  788.             cursor to the end of line (which is more logical,
  789.             but not Vi-compatible) use ":map Y y$".
  790.  
  791.                             *v_y*
  792. {Visual}["x]y        Yank the highlighted text [into register x] (for
  793.             {Visual} see |Visual-mode|).  {not in Vi}
  794.  
  795.                             *v_Y*
  796. {Visual}["x]Y        Yank the highlighted lines [into register x] (for
  797.             {Visual} see |Visual-mode|).  {not in Vi}
  798.  
  799.                             *:y* *:yank*
  800. :[range]y[ank] [x]    Yank [range] lines [into register x].
  801.  
  802. :[range]y[ank] [x] {count}
  803.             Yank {count} lines, starting with last line number
  804.             in [range] (default: current line |cmdline-ranges|),
  805.             [into register x].
  806.  
  807.                             *p* *put* *E353*
  808. ["x]p            Put the text [from register x] after the cursor
  809.             [count] times.  {Vi: no count}
  810.  
  811.                             *P*
  812. ["x]P            Put the text [from register x] before the cursor
  813.             [count] times.  {Vi: no count}
  814.  
  815.                             *<MiddleMouse>*
  816. ["x]<MiddleMouse>    Put the text from a register before the cursor [count]
  817.             times.  Uses the "* register, unless another is
  818.             specified.  Using the mouse only works when 'mouse'
  819.             contains 'n' or 'a'.
  820.             {not in Vi}
  821.  
  822.                             *gp*
  823. ["x]gp            Just like "p", but leave the cursor just after the new
  824.             text.  {not in Vi}
  825.  
  826.                             *gP*
  827. ["x]gP            Just like "P", but leave the cursor just after the new
  828.             text.  {not in Vi}
  829.  
  830.                             *:pu* *:put*
  831. :[line]pu[t] [x]    Put the text [from register x] after [line] (default
  832.             current line).  This always works linewise, thus this
  833.             command can be used to put a yanked block as new
  834.             lines.
  835.             The register can also be '=' followed by an optional
  836.             expression.  The expression continues until the end of
  837.             the command.  You need to escape the '|' and '"'
  838.             characters to prevent them from terminating the
  839.             command.  Example: >
  840.                 :put ='path' . \",/test\"
  841. <            If there is no expression after '=', Vim uses the
  842.             previous expression.  You can see it with ":dis =".
  843.  
  844. :[line]pu[t]! [x]    Put the text [from register x] before [line] (default
  845.             current line).
  846.  
  847. ["x]]p            or                    *]p* *]<MiddleMouse>*
  848. ["x]]<MiddleMouse>    Like "p", but adjust the indent to the current line.
  849.             Using the mouse only works when 'mouse' contains 'n'
  850.             or 'a'.  {not in Vi}
  851.  
  852. ["x][P            or                    *[P*
  853. ["x]]P            or                    *]P*
  854. ["x][p            or                    *[p* *[<MiddleMouse>*
  855. ["x][<MiddleMouse>    Like "P", but adjust the indent to the current line.
  856.             Using the mouse only works when 'mouse' contains 'n'
  857.             or 'a'.  {not in Vi}
  858.  
  859. You can use these commands to copy text from one place to another.  Do this
  860. by first getting the text into a register with a yank, delete or change
  861. command, then inserting the register contents with a put command.  You can
  862. also use these commands to move text from one file to another, because Vim
  863. preserves all registers when changing buffers (the CTRL-^ command is a quick
  864. way to toggle between two files).
  865.  
  866.                 *linewise-register* *characterwise-register*
  867. You can repeat the put commands with "." (except for :put) and undo them.  If
  868. the command that was used to get the text into the register was linewise, Vim
  869. inserts the text below ("p") or above ("P") the line where the cursor is.
  870. Otherwise Vim inserts the text after ("p") or before ("P") the cursor.  With
  871. the ":put" command, Vim always inserts the text in the next line.  You can
  872. exchange two characters with the command sequence "xp".  You can exchange two
  873. lines with the command sequence "ddp".  You can exchange two words with the
  874. command sequence "deep" (start with the cursor in the blank space before the
  875. first word).  You can use the "']" or "`]" command after the put command to
  876. move the cursor to the end of the inserted text, or use "'[" or "`[" to move
  877. the cursor to the start.
  878.  
  879.                         *put-Visual-mode* *v_p* *v_P*
  880. When using a put command like |p| or |P| in Visual mode, Vim will try to
  881. replace the selected text with the contents of the register.  Whether this
  882. works well depends on the type of selection and the type of the text in the
  883. register.  With blockwise selection it also depends on the size of the block
  884. and whether the corners are on an existing character. (implementation detail:
  885. it actually works by first putting the register after the selection and then
  886. deleting the selection).
  887.  
  888.                             *blockwise-register*
  889. If you use a blockwise Visual mode command to get the text into the register,
  890. the block of text will be inserted before ("P") or after ("p") the cursor
  891. column in the current and next lines.  Vim makes the whole block of text start
  892. in the same column.  Thus the inserted text looks the same as when it was
  893. yanked or deleted.  Vim may replace some <Tab> characters with spaces to make
  894. this happen.  However, if the width of the block is not a multiple of a <Tab>
  895. width and the text after the inserted block contains <Tab>s, that text may be
  896. misaligned.
  897.  
  898. Note that after a yank command, Vim leaves the cursor on the first yanked
  899. character that is closest to the start of the buffer.  This means that "yl"
  900. doesn't move the cursor, but "yh" moves the cursor one character left.
  901. Rationale:    In Vi the "y" command followed by a backwards motion would
  902.         sometimes not move the cursor to the first yanked character,
  903.         because redisplaying was skipped.  In Vim it always moves to
  904.         the first character, as specified by Posix.
  905.  
  906. There are nine types of registers:            *registers* *E354*
  907. 1. The unnamed register ""
  908. 2. 10 numbered registers "0 to "9
  909. 3. The small delete register "-
  910. 4. 26 named registers "a to "z or "A to "Z
  911. 5. four read-only registers ":, "., "% and "#
  912. 6. the expression register "=
  913. 7. The selection registers "* and "+
  914. 8. The black hole register "_
  915. 9. Last search pattern register "/
  916.  
  917. 1. Unnamed register ""                *quote_quote* *quotequote*
  918. Vim fills this register with text deleted with the "d", "c", "s", "x" commands
  919. or copied with the yank "y" command, regardless of whether or not a specific
  920. register was used (e.g.  "xdd).  An exception is the '_' register: "_dd does
  921. not store the deleted text in any register.  Vim uses the contents of this
  922. register for any put command (p or P) which does not specify a register.
  923. Additionally you can access it with the name '"'.  This means you have to type
  924. two double quotes.  Writing to the "" register writes to register "0.
  925. {Vi: register contents are lost when changing files, no '"'}
  926.  
  927. 2. Numbered registers "0 to "9        *quote_number* *quote0*    *quote1*
  928.                     *quote2* *quote3* *quote4* *quote9*
  929. Vim fills these registers with text from yank and delete commands.
  930.    Numbered register 0 contains the text from the most recent yank command,
  931. unless the command specified another register with ["x].
  932.    Numbered register 1 contains the text deleted by the most recent delete or
  933. change command, unless the command specified another register or the text is
  934. less than one line (the small delete register is used then).  An exception is
  935. made for these commands: |%|, |(|, |)|, |`|, |/|, |?|, |n|, |N|, |{| and |}|.
  936. Register "1 is always used then (this is Vi compatible).  The "- register is
  937. used as well if the delete is within a line.
  938.    With each successive deletion or change, Vim shifts the previous contents
  939. of register 1 into register 2, 2 into 3, and so forth, losing the previous
  940. contents of register 9.
  941. {Vi: numbered register contents are lost when changing files; register 0 does
  942. not exist}
  943.  
  944. 3. Small delete register "-                *quote_-* *quote-*
  945. This register contains text from commands that delete less than one line,
  946. except when the command specifies a register with ["x].
  947. {not in Vi}
  948.  
  949. 4. Named registers "a to "z or "A to "Z            *quote_alpha* *quotea*
  950. Vim fills these registers only when you say so.  Specify them as lowercase
  951. letters to replace their previous contents or as uppercase letters to append
  952. to their previous contents.
  953.  
  954. 5. Read-only registers ":, "., "% and "#
  955. These are '%', '#', ':' and '.'.  You can use them only with the "p", "P",
  956. and ":put" commands and with CTRL-R.  {not in Vi}
  957.                         *quote_.* *quote.* *E29*
  958.     ".    Contains the last inserted text (the same as what is inserted
  959.         with the insert mode commands CTRL-A and CTRL-@).  Note: this
  960.         doesn't work with CTRL-R on the command-line.  It works a bit
  961.         differently, like inserting the text instead of putting it
  962.         ('textwidth' and other options affect what is inserted).
  963.                             *quote_%* *quote%*
  964.     "%    Contains the name of the current file.
  965.                             *quote_#* *quote#*
  966.     "#    Contains the name of the alternate file.
  967.                         *quote_:* *quote:* *E30*
  968.     ":    Contains the most recent executed command-line.  Example: Use
  969.         "@:" to repeat the previous command-line command.
  970.         The command-line is only stored in this register when at least
  971.         one character of it was typed.  Thus it remains unchanged if
  972.         the command was completely from a mapping.
  973.         {not available when compiled without the |+cmdline_hist|
  974.         feature}
  975.  
  976. 6. Expression register "=                *quote_=* *quote=*
  977. This is not really a register that stores text, but is a way to use an
  978. expression in commands which use a register.  The expression register is
  979. read-only; you cannot put text into it.  After the '=', the cursor moves to
  980. the command-line, where you can enter any expression (see |expression|).  All
  981. normal command-line editing commands are available, including a special
  982. history for expressions.  When you end the command-line by typing <CR>, Vim
  983. computes the result of the expression.  If you end it with <Esc>, Vim abandons
  984. the expression.  If you do not enter an expression, Vim uses the previous
  985. expression (like with the "/" command).  If the "= register is used for the
  986. "p" command, the string is split up at <NL> characters.  If the string ends in
  987. a <NL>, it is regarded as a linewise register.  {not in Vi}
  988.  
  989. 7. Selection registers "* and "+
  990. Use these register for storing and retrieving the selected text for the GUI.
  991. See |quotestar| and |quoteplus|.  When the clipboard is not available or not
  992. working, the unnamed register is used instead.  {not in Vi}
  993.  
  994. Note that there is only a distinction between "* and "+ for X11 systems.  For
  995. an explanation of the difference, see |x11-selection|.  Under MS-Windows, use
  996. of "* and "+ is actually synonymous and refers to the |gui-clipboard|.
  997.  
  998. 8. Black hole register "_                *quote_*
  999. When writing to this register, nothing happens.  This can be used to delete
  1000. text without affecting the normal registers.  When reading from this register,
  1001. nothing is returned.  {not in Vi}
  1002.  
  1003. 9. Last search pattern register    "/            *quote_/* *quote/*
  1004. Contains the most recent search-pattern.  This is used for "n" and 'hlsearch'.
  1005. It is writable with ":let", you can change it to have 'hlsearch' highlight
  1006. other matches without actually searching.  You can't yank or delete into this
  1007. register.  {not in Vi}
  1008.  
  1009.                             *@/*
  1010. You can write to a register with a ":let" command |:let-@|.  Example: >
  1011.     :let @/ = "the"
  1012.  
  1013. If you use a put command without specifying a register, Vim uses the register
  1014. that was last filled (this is also the contents of the unnamed register).  If
  1015. you are confused, use the ":dis" command to find out what Vim will put (this
  1016. command displays all named and numbered registers; the unnamed register is
  1017. labelled '"').
  1018.  
  1019. The next three commands always work on whole lines.
  1020.  
  1021. :[range]co[py] {address}                *:co* *:copy*
  1022.             Copy the lines given by [range] to below the line
  1023.             given by {address}.
  1024.  
  1025.                             *:t*
  1026. :t            Synonym for copy.
  1027.  
  1028. :[range]m[ove] {address}            *:m* *:mo* *:move* *E134*
  1029.             Move the lines given by [range] to below the line
  1030.             given by {address}.
  1031.  
  1032. ==============================================================================
  1033. 6. Formatting text                    *formatting*
  1034.  
  1035. :[range]ce[nter] [width]                *:ce* *:center*
  1036.             Center lines in [range] between [width] columns
  1037.             (default 'textwidth' or 80 when 'textwidth' is 0).
  1038.             {not in Vi}
  1039.             Not available when |+ex_extra| feature was disabled at
  1040.             compile time.
  1041.  
  1042. :[range]ri[ght] [width]                    *:ri* *:right*
  1043.             Right-align lines in [range] at [width] columns
  1044.             (default 'textwidth' or 80 when 'textwidth' is 0).
  1045.             {not in Vi}
  1046.             Not available when |+ex_extra| feature was disabled at
  1047.             compile time.
  1048.  
  1049.                             *:le* *:left*
  1050. :[range]le[ft] [indent]
  1051.             Left-align lines in [range].  Sets the indent in the
  1052.             lines to [indent] (default 0).  {not in Vi}
  1053.             Not available when |+ex_extra| feature was disabled at
  1054.             compile time.
  1055.  
  1056.                             *gq*
  1057. gq{motion}        Format the lines that {motion} moves over.  The
  1058.             'textwidth' option controls the length of each
  1059.             formatted line (see below).  If the 'textwidth' option
  1060.             is 0, the formatted line length is the screen width
  1061.             (with a maximum width of 79).  {not in Vi}
  1062.             The 'formatoptions' option controls the type of
  1063.             formatting |fo-table|.
  1064.             NOTE: The "Q" command formerly performed this
  1065.             function.  If you still want to use "Q" for
  1066.             formatting, use this mapping: >
  1067.                 :nnoremap Q gq
  1068.  
  1069. gqgq                            *gqgq* *gqq*
  1070. gqq            Format the current line.  {not in Vi}
  1071.  
  1072.                             *v_gq*
  1073. {Visual}gq        Format the highlighted text.  (for {Visual} see
  1074.             |Visual-mode|).  {not in Vi}
  1075.  
  1076. Example: To format the current paragraph use: >
  1077.     gqap
  1078.  
  1079. The "gq" command leaves the cursor in the line where the motion command takes
  1080. the cursor.  This allows you to repeat formatting repeated with ".".  This
  1081. works well with "gqj" (format current and next line) and "gq}" (format until
  1082. end of paragraph).  Note: When 'formatprg' is set, "gq" leaves the cursor on
  1083. the first formatted line (as with using a filter command).
  1084.  
  1085. If the 'autoindent' option is on, Vim uses the indent of the first line for
  1086. the following lines.
  1087.  
  1088. Formatting does not change empty lines (but it does change lines with only
  1089. white space!).
  1090.  
  1091. The 'joinspaces' option is used when lines are joined together.
  1092.  
  1093. You can set the 'formatprg' option to the name of an external program for Vim
  1094. to use for text formatting.  The 'textwidth' and other options have no effect
  1095. on formatting by an external program.
  1096.  
  1097.                             *right-justify*
  1098. There is no command in Vim to right justify text.  You can do it with
  1099. an external command, like "par" (e.g.: "!}par" to format until the end of the
  1100. paragraph) or set 'formatprg' to "par".
  1101.  
  1102.                             *format-comments*
  1103. Vim can format comments in a special way.  Vim recognizes a comment by a
  1104. specific string at the start of the line (ignoring white space).  Three types
  1105. of comments can be used:
  1106.  
  1107. - A comment string that repeats at the start of each line.  An example is the
  1108.   type of comment used in shell scripts, starting with "#".
  1109. - A comment string that occurs only in the first line, not in the following
  1110.   lines.  An example is this list with dashes.
  1111. - Three-piece comments that have a start string, an end string, and optional
  1112.   lines in between.  The strings for the start, middle and end are different.
  1113.   An example is the C-style comment:
  1114.     /*
  1115.      * this is a C comment
  1116.      */
  1117.  
  1118. The 'comments' option is a comma-separated list of parts.  Each part defines a
  1119. type of comment string.  A part consists of:
  1120.     {flags}:{string}
  1121.  
  1122. {string} is the literal text that must appear.
  1123.  
  1124. {flags}:
  1125.   n    Nested comment.  Nesting with mixed parts is allowed.  If 'comments'
  1126.     is "n:),n:>" a line starting with "> ) >" is a comment.
  1127.  
  1128.   b    Blank (<Space>, <Tab> or <EOL>) required after {string}.
  1129.  
  1130.   f    Only the first line has the comment string.  Do not repeat comment on
  1131.     the next line, but preserve indentation (e.g., a bullet-list).
  1132.  
  1133.   s    Start of three-piece comment
  1134.  
  1135.   m    Middle of a three-piece comment
  1136.  
  1137.   e    End of a three-piece comment
  1138.  
  1139.   l    Left adjust middle with start or end (default).  Only recognized when
  1140.     used together with 's' or 'e'.
  1141.  
  1142.   r    Right adjust middle with start or end.  Only recognized when used
  1143.     together with 's' or 'e'.
  1144.  
  1145.   O    Don't use this one for the "O" command.
  1146.  
  1147.   x    Allows three-piece comments to be ended by just typing the last
  1148.     character of the end-comment string as the first character on a new
  1149.     line, when the middle-comment string has already been inserted
  1150.     automatically.  See below for more details.
  1151.  
  1152.   {digits}
  1153.     When together with 's' or 'e': add extra indent for the middle part.
  1154.     This can be used to left-align the middle part with the start or end
  1155.     and then add an offset.
  1156.  
  1157.   -{digits}
  1158.     Like {digits} but reduce the indent.  This only works when there is
  1159.     some indent for the start or end part that can be removed.
  1160.  
  1161. When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the
  1162. comment string repeats at the start of each line.  The flags field may be
  1163. empty.
  1164.  
  1165. Any blank space in the text before and after the {string} is part of the
  1166. {string}, so do not include leading or trailing blanks unless the blanks are a
  1167. required part of the comment string.
  1168.  
  1169. When one comment leader is part of another, specify the part after the whole.
  1170. For example, to include both "-" and "->", use >
  1171.     :set comments=f:->,f:-
  1172.  
  1173. A three-piece comment must always be given as start,middle,end, with no other
  1174. parts in between.  An example of a three-piece comment is >
  1175.     sr:/*,mb:*,ex:*/
  1176. for C-comments.  To avoid recognizing "*ptr" as a comment, the middle string
  1177. includes the 'b' flag.  For three-piece comments, Vim checks the text after
  1178. the start and middle strings for the end string.  If Vim finds the end string,
  1179. the comment does not continue on the next line.  Three-piece comments must
  1180. have a middle string because otherwise Vim can't recognize the middle lines.
  1181.  
  1182. Notice the use of the "x" flag in the above three-piece comment definition.
  1183. When you hit Return in a C-comment, Vim will insert the middle comment leader
  1184. for the new line, e.g. " * ".  To close this comment you just have to type "/"
  1185. before typing anything else on the new line.  This will replace the
  1186. middle-comment leader with the end-comment leader, leaving just " */".  There
  1187. is no need to hit BackSpace first.
  1188.  
  1189. Examples: >
  1190.    "b:*"    Includes lines starting with "*", but not if the "*" is
  1191.         followed by a non-blank.  This avoids a pointer dereference
  1192.         like "*str" to be recognized as a comment.
  1193.    "n:>"    Includes a line starting with ">", ">>", ">>>", etc.
  1194.    "fb:-"    Format a list that starts with "- ".
  1195.  
  1196. By default, "b:#" is included.  This means that a line that starts with
  1197. "#include" is not recognized as a comment line.  But a line that starts with
  1198. "# define" is recognized.  This is a compromise.
  1199.  
  1200. Often the alignment can be changed from right alignment to a left alignment
  1201. with an additional space.  For example, for Javadoc comments, this can be
  1202. used (insert a backslash before the space when using ":set"): >
  1203.     s1:/*,mb:*,ex:*/
  1204. Note that an offset is included with start, so that the middle part is left
  1205. aligned with the start and then an offset of one character added.  This makes
  1206. it possible to left align the start and middle for this construction: >
  1207.     /**
  1208.      * comment
  1209.      */
  1210.  
  1211. {not available when compiled without the |+comments| feature}
  1212.  
  1213.                             *fo-table*
  1214. You can use the 'formatoptions' option  to influence how Vim formats text.
  1215. 'formatoptions' is a string that can contain any of the letters below.  The
  1216. default setting is "tcq".  You can separate the option letters with commas for
  1217. readability.
  1218.  
  1219. letter     meaning when present in 'formatoptions'    ~
  1220.  
  1221. t    Auto-wrap text using textwidth (does not apply to comments)
  1222. c    Auto-wrap comments using textwidth, inserting the current comment
  1223.     leader automatically.
  1224. r    Automatically insert the current comment leader after hitting
  1225.     <Enter> in Insert mode.
  1226. o    Automatically insert the current comment leader after hitting 'o' or
  1227.     'O' in Normal mode.
  1228. q    Allow formatting of comments with "gq".
  1229.     Note that formatting will not change blank lines or lines containing
  1230.     only the comment leader.  A new paragraph starts after such a line,
  1231.     or when the comment leader changes.
  1232. n    When formatting text, recognize numbered lists.  The indent of the
  1233.     text after the number is used for the next line.  The number may
  1234.     optionally be followed by '.', ':', ')', ']' or '}'.  Note that
  1235.     'autoindent' must be set too.
  1236.     Example: >
  1237.         1. the first item
  1238.            wraps
  1239.         2. the second item
  1240. 2    When formatting text, use the indent of the second line of a paragraph
  1241.     for the rest of the paragraph, instead of the indent of the first
  1242.     line.  This supports paragraphs in which the first line has a
  1243.     different indent than the rest.  Note that 'autoindent' must be set
  1244.     too.  Example: >
  1245.             first line of a paragraph
  1246.         second line of the same paragraph
  1247.         third line.
  1248. v    Vi-compatible auto-wrapping in insert mode: Only break a line at a
  1249.     blank that you have entered during the current insert command.  (Note:
  1250.     this is not 100% Vi compatible.  Vi has some "unexpected features" or
  1251.     bugs in this area.  It uses the screen column instead of the line
  1252.     column.)
  1253. b    Like 'v', but only auto-wrap if you enter a blank at or before
  1254.     the wrap margin.  If the line was longer than 'textwidth' when you
  1255.     started the insert, or you do not enter a blank in the insert before
  1256.     reaching 'textwidth', Vim does not perform auto-wrapping.
  1257. l    Long lines are not broken in insert mode: When a line was longer than
  1258.     'textwidth' when the insert command started, Vim does not
  1259.     automatically format it.
  1260. m    Also break at a multi-byte character above 255.  This is useful for
  1261.     Asian text where every character is a word on its own.
  1262. 1    Don't break a line after a one-letter word.  It's broken before it
  1263.     instead (if possible).
  1264.  
  1265.  
  1266. With 't' and 'c' you can specify when Vim performs auto-wrapping:
  1267. value    action    ~
  1268. ""    no automatic formatting (you can use "gq" for manual formatting)
  1269. "t"    automatic formatting of text, but not comments
  1270. "c"    automatic formatting for comments, but not text (good for C code)
  1271. "tc"    automatic formatting for text and comments
  1272.  
  1273. Note that when 'textwidth' is 0, Vim does no formatting anyway (but does
  1274. insert comment leaders according to the 'comments' option).
  1275.  
  1276. Note that when 'paste' is on, Vim does no formatting at all.
  1277.  
  1278. Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping;
  1279. 'textwidth' is still useful for formatting with "gq".
  1280.  
  1281. If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some
  1282. built in stuff to treat these types of comments a bit more cleverly.
  1283. Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in
  1284. 'formatoptions') gives the correct start of the line automatically.  The same
  1285. happens with formatting and auto-wrapping. Opening a line after a line
  1286. starting with "/*" or "*" and containing "*/", will cause no comment leader to
  1287. be inserted, and the indent of the new line is taken from the line containing
  1288. the start of the comment.
  1289. E.g.:
  1290.     /* ~
  1291.      * Your typical comment. ~
  1292.      */ ~
  1293.     The indent on this line is the same as the start of the above
  1294.     comment.
  1295.  
  1296. All of this should be really cool, especially in conjunction with the new
  1297. :autocmd command to prepare different settings for different types of file.
  1298.  
  1299. Some examples:
  1300.   for C code (only format comments): >
  1301.     :set fo=croq
  1302. < for Mail/news    (format all, don't start comment with "o" command): >
  1303.     :set fo=tcrq
  1304. <
  1305.  vim:tw=78:ts=8:ft=help:norl:
  1306.